home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Resources / Online / Miami / MiamiSDK / doc / Socket.doc < prev    next >
Text File  |  1997-12-27  |  74KB  |  2,402 lines
  1. TABLE OF CONTENTS
  2.  
  3. bsdsocket.library/accept
  4. bsdsocket.library/bind
  5. bsdsocket.library/CloseSocket
  6. bsdsocket.library/connect
  7. bsdsocket.library/Dup2Socket
  8. bsdsocket.library/Errno
  9. bsdsocket.library/getdtablesize
  10. bsdsocket.library/gethostbyaddr
  11. bsdsocket.library/gethostbyname
  12. bsdsocket.library/gethostid
  13. bsdsocket.library/gethostname
  14. bsdsocket.library/getnetbyaddr
  15. bsdsocket.library/getnetbyname
  16. bsdsocket.library/getpeername
  17. bsdsocket.library/getprotobyname
  18. bsdsocket.library/getprotobynumber
  19. bsdsocket.library/getservbyname
  20. bsdsocket.library/getservbyport
  21. bsdsocket.library/GetSocketEvents
  22. bsdsocket.library/getsockname
  23. bsdsocket.library/getsockopt
  24. bsdsocket.library/inet_addr
  25. bsdsocket.library/inet_lnaof
  26. bsdsocket.library/Inet_LnaOf
  27. bsdsocket.library/inet_makeaddr
  28. bsdsocket.library/Inet_MakeAddr
  29. bsdsocket.library/inet_netof
  30. bsdsocket.library/Inet_NetOf
  31. bsdsocket.library/inet_network
  32. bsdsocket.library/inet_ntoa
  33. bsdsocket.library/Inet_NtoA
  34. bsdsocket.library/IoctlSocket
  35. bsdsocket.library/listen
  36. bsdsocket.library/ObtainSocket
  37. bsdsocket.library/recv
  38. bsdsocket.library/recvfrom
  39. bsdsocket.library/recvmsg
  40. bsdsocket.library/ReleaseCopyOfSocket
  41. bsdsocket.library/ReleaseSocket
  42. bsdsocket.library/select
  43. bsdsocket.library/send
  44. bsdsocket.library/sendmsg
  45. bsdsocket.library/sendto
  46. bsdsocket.library/SetErrnoPtr
  47. bsdsocket.library/SetSocketSignals
  48. bsdsocket.library/setsockopt
  49. bsdsocket.library/shutdown
  50. bsdsocket.library/socket
  51. bsdsocket.library/SocketBaseTagList
  52. bsdsocket.library/vsyslog
  53. bsdsocket.library/WaitSelect
  54. bsdsocket.library/accept                 bsdsocket.library/accept
  55.  
  56.    NAME
  57.     accept -- accept a connection on a socket
  58.  
  59.    SYNOPSIS
  60.     news = accept( s, addr, addrlen );
  61.     D0           D0 A0    A1
  62.  
  63.     long accept( long s, struct sockaddr *addr, long *addrlen );
  64.  
  65.    FUNCTION
  66.     The argument s is a socket that has been created with socket(), bound
  67.     to an address with bind(), and is listening for connections after a
  68.     listen().  The accept() argument extracts the first connection
  69.     request on the queue of pending connections, creates a new socket
  70.     with the same properties of s and allocates a new file descriptor for
  71.     the socket.  If no pending connections are present on the queue, and
  72.     the socket is not marked as non-blocking, accept() blocks the caller
  73.     until a connection is present.    If the socket is marked non-blocking
  74.     and no pending connections are present on the queue, accept() returns
  75.     an error as described below.  The accepted socket may not be used to
  76.     accept more connections.  The original socket s remains open.
  77.  
  78.     The argument addr is a result parameter that is filled in with the
  79.     address of the connecting entity, as known to the communications
  80.     layer.    The exact format of the addr parameter is determined by the
  81.     domain in which the communication is occurring.  The addrlen is a
  82.     value-result parameter; it should initially contain the amount of
  83.     space pointed to by addr; on return it will contain the actual length
  84.     (in bytes) of the address returned.  This call is used with
  85.     connection-based socket types, currently with SOCK_STREAM.
  86.  
  87.     It is possible to select() a socket for the purposes of doing an
  88.     accept() by selecting it for read.
  89.  
  90.     One can obtain user connection request data without confirming the
  91.     connection by issuing a recvmsg() call with an msg_iovlen of 0 and a
  92.     non-zero msg_controllen, or by issuing a getsockopt() request.
  93.     Similarly, one can provide user connection rejection information by
  94.     issuing a sendmsg() call with providing only the control information,
  95.     or by calling setsockopt().
  96.  
  97.     The call returns -1 on error.  If it succeeds, it returns a
  98.     non-negative integer that is a descriptor for the accepted socket.
  99.  
  100.     The accept() will fail if:
  101.  
  102.     [EBADF] The descriptor is invalid.
  103.  
  104.     [EOPNOTSUPP] The referenced socket is not of type SOCK_STREAM.
  105.  
  106.     [EWOULDBLOCK] The socket is marked non-blocking and no connections
  107.     are present to be accepted.
  108.  
  109.    INPUTS
  110.     s - socket
  111.  
  112.     addr - address
  113.  
  114.     addrlen - pointer to address length
  115.  
  116.    RESULT
  117.     news (D0) - new socket
  118.  
  119. bsdsocket.library/bind                       bsdsocket.library/bind
  120.  
  121.    NAME
  122.     bind -- bind a name to a socket
  123.  
  124.    SYNOPSIS
  125.     ret = bind( s, name, namelen );
  126.     D0        D0 A0    D1
  127.  
  128.     long bind( long s, struct sockaddr *name, long namelen );
  129.  
  130.    FUNCTION
  131.     bind() assigns a name to an unnamed socket.  When a socket is created
  132.     with socket() it exists in a name space (address family) but has no
  133.     name assigned.    bind() requests that name be assigned to the socket.
  134.  
  135.     The rules used in name binding vary between communication domains.
  136.     For the Internet domain (AF_INET) the name has to be passed in a
  137.     "struct sockaddr_in".
  138.  
  139.     If the bind is successful, a 0 value is returned.  A return value of
  140.     -1 indicates an error, which is further specified in the return value
  141.     of Errno().
  142.  
  143.     The bind() call will fail if:
  144.  
  145.     [EBADF] s is not a valid descriptor.
  146.  
  147.     [EADDRNOTAVAIL] The specified address is not available from the local
  148.     machine.
  149.  
  150.     [EADDRINUSE] The specified address is already in use.
  151.  
  152.     [EINVAL] The socket is already bound to an address.
  153.  
  154.    INPUTS
  155.     s - socket
  156.  
  157.     name - name (address)
  158.  
  159.     namelen - name length
  160.  
  161.    RESULT
  162.     ret (D0) - return value
  163.  
  164. bsdsocket.library/CloseSocket            bsdsocket.library/CloseSocket
  165.  
  166.    NAME
  167.     CloseSocket -- Close a socket
  168.  
  169.    SYNOPSIS
  170.     ret = CloseSocket( s  );
  171.     D0           D0
  172.  
  173.     long CloseSocket( long s );
  174.  
  175.    FUNCTION
  176.     The CloseSocket() call deletes a descriptor from the per-process
  177.     socket reference table.  If this is the last reference to the
  178.     underlying object, the socket will be closed, and associated naming
  179.     information and queued data are discarded.
  180.  
  181.     When a process exits and closes bsdsocket.library, all associated
  182.     socket descriptors are freed, but since there is a limit on active
  183.     descriptors per processes, the CloseSocket() function call is useful
  184.     when a large quantity of socket descriptors are being handled.
  185.  
  186.     Upon successful completion, a value of 0 is returned.  Otherwise, a
  187.     value of -1 is returned and the return value of Errno() is set to
  188.     indicate the error.
  189.  
  190.     CloseSocket() will fail if:
  191.  
  192.     [EBADF] s is not an active socket descriptor.
  193.  
  194.    INPUTS
  195.     s - socket
  196.  
  197.    RESULT
  198.     ret (D0) - return value
  199.  
  200. bsdsocket.library/connect                bsdsocket.library/connect
  201.  
  202.    NAME
  203.     connect -- initiate a connection on a socket
  204.  
  205.    SYNOPSIS
  206.     ret = connect( s, name, namelen );
  207.     D0           D0 A0    D0
  208.  
  209.     long connect( long s, struct sockaddr *name, long namelen );
  210.  
  211.    FUNCTION
  212.     The parameter s is a socket.  If it is of type SOCK_DGRAM, this call
  213.     specifies the peer with which the socket is to be associated; this
  214.     address is that to which datagrams are to be sent, and the only
  215.     address from which datagrams are to be received.  If the socket is of
  216.     type SOCK_STREAM, this call attempts to make a connection to another
  217.     socket.  The other socket is specified by name, which is an address
  218.     in the communications space of the socket.  Each communications space
  219.     interprets the name parameter in its own way.  Generally, stream
  220.     sockets may successfully connect() only once; datagram sockets may
  221.     use connect() multiple times to change their association.  Datagram
  222.     sockets may dissolve the association by connecting to an invalid
  223.     address, such as a null address.
  224.  
  225.     If the connection or binding succeeds, 0 is returned.  Otherwise a -1
  226.     is returned, and a more specific error code is stored in errno.
  227.  
  228.     The connect() call fails if:
  229.  
  230.     [EBADF] S is not a valid descriptor.
  231.  
  232.     [EADDRNOTAVAIL] The specified address is not available on this
  233.     machine.
  234.  
  235.     [EAFNOSUPPORT] Addresses in the specified address family cannot be
  236.     used with this socket.
  237.  
  238.     [EISCONN] The socket is already connected.
  239.  
  240.     [ETIMEDOUT] Connection establishment timed out without establishing a
  241.     connection.
  242.  
  243.     [ECONNREFUSED] The attempt to connect was forcefully rejected.
  244.  
  245.     [ENETUNREACH] The network isn't reachable from this host.
  246.  
  247.     [EADDRINUSE] The address is already in use.
  248.  
  249.     [EINPROGRESS] The socket is non-blocking and the connection cannot be
  250.     completed immediately.    It is possible to select() for completion by
  251.     selecting the socket for writing.
  252.  
  253.     [EALREADY] The socket is non-blocking and a previous connection
  254.     attempt has not yet been completed.
  255.  
  256.    INPUTS
  257.     s - socket
  258.  
  259.     name - name (address)
  260.  
  261.     namelen - name length
  262.  
  263.    RESULT
  264.     ret (D0) - return value
  265.  
  266. bsdsocket.library/Dup2Socket             bsdsocket.library/Dup2Socket
  267.  
  268.    NAME
  269.     Dup2Socket -- duplicate an existing socket descriptor
  270.  
  271.    SYNOPSIS
  272.     s  = Dup2Socket( olds, news );
  273.     D0         D0    D1
  274.  
  275.     long Dup2Socket( long olds, long news );
  276.  
  277.    FUNCTION
  278.     Dup2Socket() duplicates an existing socket descriptor and returns its
  279.     value to the calling process.  The argument olds is a small
  280.     non-negative integer index in the per-process descriptor table.  The
  281.     value must be less than the size of the table, which is returned by
  282.     getdtablesize().  The value of the new descriptor news is specified
  283.     in the call as well.  If this descriptor is already in use, the
  284.     descriptor is first deallocated as if a CloseSocket() call had been
  285.     done first.  If -1 is passed as the new descriptor then the lowest
  286.     available descriptor will be used.
  287.  
  288.     The socket referenced by the descriptor does not distinguish between
  289.     olds and news in any way.
  290.  
  291.     The value -1 is returned if an error occurs in either call.  The
  292.     return value of Errno() indicates the cause of the error.
  293.  
  294.     Dup2Socket() fail if:
  295.  
  296.     [EBADF] olds or news is not a valid active descriptor
  297.  
  298.    INPUTS
  299.     olds - old socket descriptor
  300.  
  301.     news - new socket descriptor
  302.  
  303.    RESULT
  304.     s (D0) - new allocated socket descriptor
  305.  
  306. bsdsocket.library/Errno                   bsdsocket.library/Errno
  307.  
  308.    NAME
  309.     Errno -- return the current error code
  310.  
  311.    SYNOPSIS
  312.     err = Errno();
  313.     D0
  314.  
  315.     long Errno (void);
  316.  
  317.    FUNCTION
  318.     Errno() returns the value of the errno variable used in the process
  319.     instance data of the protocol stack.
  320.  
  321.    RESULT
  322.     err (D0) - current error code
  323.  
  324. bsdsocket.library/getdtablesize           bsdsocket.library/getdtablesize
  325.  
  326.    NAME
  327.     getdtablesize -- get descriptor table size
  328.  
  329.    SYNOPSIS
  330.     size = getdtablesize();
  331.     D0
  332.  
  333.     long getdtablesize (void);
  334.  
  335.    FUNCTION
  336.     Each process has a fixed size descriptor table, which is guaranteed
  337.     to have at least 20 slots.  The entries in the descriptor table are
  338.     numbered with small integers starting at 0.  The call getdtablesize()
  339.     returns the size of this table.
  340.  
  341.    RESULT
  342.     size (D0) - descriptor table size
  343.  
  344. bsdsocket.library/gethostbyaddr           bsdsocket.library/gethostbyaddr
  345.  
  346.    NAME
  347.     gethostbyaddr -- get network host entry
  348.  
  349.    SYNOPSIS
  350.     he = gethostbyaddr( addr, len, type );
  351.     D0            A0      D0   D1
  352.  
  353.     struct hostent *gethostbyaddr( char *addr, long len, long type );
  354.  
  355.    FUNCTION
  356.     The gethostbyaddr() function returns a pointer to an object with the
  357.     following structure describing an internet host referenced by name or
  358.     by address, respectively.  This structure contains either the
  359.     information obtained from the DNS name server, or broken-out fields
  360.     from a configuration entry in the local host table.
  361.  
  362.     struct    hostent {
  363.         char    *h_name;    /* official name of host */
  364.         char    **h_aliases;    /* alias list */
  365.         int    h_addrtype;    /* host address type */
  366.         int    h_length;    /* length of address */
  367.         char    **h_addr_list;    /* list of addresses from
  368.                        name server */
  369.     };
  370.     #define h_addr    h_addr_list[0]    /* address, for backward
  371.                        compatibility */
  372.  
  373.     The members of this structure are:
  374.  
  375.     h_name Official name of the host.
  376.  
  377.     h_aliases A zero terminated array of alternate names for the host.
  378.  
  379.     h_addrtype The type of address being returned; currently always
  380.     AF_INET.
  381.  
  382.     h_length The length, in bytes, of the address.
  383.  
  384.     h_addr_list A zero terminated array of network addresses for the
  385.     host.  Host addresses are returned in network byte order.
  386.  
  387.     h_addr The first address in h_addr_list; this is for backward
  388.     compatibility.
  389.  
  390.     Error return status from gethostbyaddr() is indicated by return of a
  391.     null pointer.  The variable h_errno may then be checked to see
  392.     whether this is a temporary failure or an invalid or unknown host, by
  393.     calling SocketBaseTags with a code of SBTC_HERRNO.
  394.  
  395.     The variable h_errno can have the following values:
  396.  
  397.     HOST_NOT_FOUND No such host is known.
  398.  
  399.     TRY_AGAIN This is usually a temporary error and means that the local
  400.     server did not receive a response from an authoritative server.  A
  401.     retry at some later time may succeed.
  402.  
  403.     NO_RECOVERY Some unexpected server failure was encountered.  This is
  404.     a non-recoverable error.
  405.  
  406.     NO_DATA The requested name is valid but does not have an IP address;
  407.     this is not a temporary error.    This means that the name is known to
  408.     the name server but there is no address associated with this name.
  409.     Another type of request to the name server using this domain name
  410.     will result in an answer; for example, a mail-forwarder may be
  411.     registered for this domain.
  412.  
  413.    INPUTS
  414.     addr - address
  415.  
  416.     len - address length
  417.  
  418.     type - address type
  419.  
  420.    RESULT
  421.     he (D0) - host entry
  422.  
  423. bsdsocket.library/gethostbyname           bsdsocket.library/gethostbyname
  424.  
  425.    NAME
  426.     gethostbyname -- get network host entry
  427.  
  428.    SYNOPSIS
  429.     he = gethostbyname( name );
  430.     D0            A0
  431.  
  432.     struct hostent *gethostbyname( char *name );
  433.  
  434.    FUNCTION
  435.     The gethostbyname() function returns a pointer to an object
  436.     describing an internet host.  Please see the description of
  437.     gethostbyaddr() for more information on that structure and on
  438.     possible error conditions.
  439.  
  440.    INPUTS
  441.     name - host name
  442.  
  443.    RESULT
  444.     he (D0) - host entry
  445.  
  446. bsdsocket.library/gethostid              bsdsocket.library/gethostid
  447.  
  448.    NAME
  449.     gethostid -- get unique identifier of current host
  450.  
  451.    SYNOPSIS
  452.     id = gethostid();
  453.     D0
  454.  
  455.     long gethostid (void);
  456.  
  457.    FUNCTION
  458.     Each Internet host is supposed to have a 32-bit identifier that is
  459.     unique among all systems in existence.    This is normally an IP
  460.     address for the local machine.
  461.  
  462.     gethostid() returns the 32-bit identifier for the current machine.
  463.  
  464.     This function has been deprecated.  DO NOT assume that the value
  465.     returned by gethostid() is a valid IP address.
  466.  
  467.    RESULT
  468.     id (D0) - hostid
  469.  
  470. bsdsocket.library/gethostname            bsdsocket.library/gethostname
  471.  
  472.    NAME
  473.     gethostname -- get name of current host
  474.  
  475.    SYNOPSIS
  476.     ret = gethostname( name, namelen );
  477.     D0           A0     D0
  478.  
  479.     long gethostname( char *name, long namelen );
  480.  
  481.    FUNCTION
  482.     gethostname() returns the standard host name for the current machine.
  483.     The parameter namelen specifies the size of the name array.  The
  484.     returned name is null-terminated unless insufficient space is
  485.     provided.
  486.  
  487.     If the call succeeds a value of 0 is returned.    If the call fails, a
  488.     value of -1 is returned and an error code is placed in the global
  489.     location errno.
  490.  
  491.    INPUTS
  492.     name - host name buffer
  493.  
  494.     namelen - length of host name buffer
  495.  
  496.    RESULT
  497.     ret (D0) - return code
  498.  
  499. bsdsocket.library/getnetbyaddr               bsdsocket.library/getnetbyaddr
  500.  
  501.    NAME
  502.     getnetbyaddr -- get network entry
  503.  
  504.    SYNOPSIS
  505.     netent = getnetbyaddr( net, type );
  506.     D0               D0   D1
  507.  
  508.     struct netent *getnetbyaddr( long net, long type );
  509.  
  510.    FUNCTION
  511.     The getnetbyaddr() function returns a pointer to an object with the
  512.     following structure containing the broken-out fields of an entry in
  513.     the local network data base.
  514.  
  515.      struct  netent {
  516.        char        *n_name;       /* official name of net */
  517.        char        **n_aliases;    /* alias list */
  518.        int           n_addrtype;       /* net number type */
  519.        unsigned long   n_net;       /* net number */
  520.      };
  521.  
  522.     The members of this structure are:
  523.  
  524.     n_name The official name of the network.
  525.  
  526.     n_aliases A zero terminated list of alternate names for the network.
  527.  
  528.     n_addrtype The type of the network number returned; currently only
  529.     AF_INET.
  530.  
  531.     n_net The network number.  Network numbers are returned in machine
  532.     byte order.
  533.  
  534.     The getnetbyaddr() function sequentially searches from the beginning
  535.     of the table until a matching net address and type is found, or until
  536.     the end of the table is reached.  Network numbers are supplied in
  537.     host order.
  538.  
  539.    INPUTS
  540.     net - network
  541.  
  542.     type - network type
  543.  
  544.    RESULT
  545.     netent (D0) - network entry
  546.  
  547. bsdsocket.library/getnetbyname               bsdsocket.library/getnetbyname
  548.  
  549.    NAME
  550.     getnetbyname -- get network entry
  551.  
  552.    SYNOPSIS
  553.     netent = getnetbyname( name );
  554.     D0               A0
  555.  
  556.     struct netent *getnetbyname( const unsigned char *name );
  557.  
  558.    FUNCTION
  559.     The getnetbyname() function returns a pointer to an object which
  560.     represents a network entry in the local network data base.  Please
  561.     see the description of getnetbyaddr() for more information on that
  562.     structure and on possible error conditions.
  563.  
  564.    INPUTS
  565.     name - network name
  566.  
  567.    RESULT
  568.     netent (D0) - network entry
  569.  
  570. bsdsocket.library/getpeername            bsdsocket.library/getpeername
  571.  
  572.    NAME
  573.     getpeername -- get name of connected peer
  574.  
  575.    SYNOPSIS
  576.     ret = getpeername( s, name, namelen );
  577.     D0           D0 A0    A1
  578.  
  579.     long getpeername( long s, struct sockaddr *name, long *namelen );
  580.  
  581.    FUNCTION
  582.     getpeername() returns the name of the peer connected to socket s.
  583.     The namelen parameter should be initialized to indicate the amount of
  584.     space pointed to by name.  On return it contains the actual size of
  585.     the name returned (in bytes).  The name is truncated if the buffer
  586.     provided is too small.
  587.  
  588.     A 0 is returned if the call succeeds, -1 if it fails.
  589.  
  590.     The call succeeds unless:
  591.  
  592.     [EBADF] The argument s is not a valid descriptor.
  593.  
  594.     [ENOTCONN] The socket is not connected.
  595.  
  596.     [ENOBUFS] Insufficient resources were available in the system to
  597.     perform the operation.
  598.  
  599.    INPUTS
  600.     s - socket
  601.  
  602.     name - name (address) buffer
  603.  
  604.     namelen - size of name buffer
  605.  
  606.    RESULT
  607.     ret (D0) - return code
  608.  
  609. bsdsocket.library/getprotobyname         bsdsocket.library/getprotobyname
  610.  
  611.    NAME
  612.     getprotobyname -- get protocol entry
  613.  
  614.    SYNOPSIS
  615.     proto = getprotobyname( name );
  616.     D0            A0
  617.  
  618.     struct protoent *getprotobyname( char *name );
  619.  
  620.    FUNCTION
  621.     The getprotobyname() function returns a pointer to an object with the
  622.     following structure containing the broken-out fields of an entry in
  623.     the local network protocol data base.
  624.  
  625.     struct    protoent {
  626.       char      *p_name;      /* official name of protocol */
  627.       char      **p_aliases;      /* alias list */
  628.       int      p_proto;      /* protocol number */
  629.     };
  630.  
  631.     The members of this structure are:
  632.  
  633.     p_name The official name of the protocol.
  634.  
  635.     p_aliases A zero terminated list of alternate names for the protocol.
  636.  
  637.     p_proto The protocol number.
  638.  
  639.     The getprotobyname() function sequentially searches from the
  640.     beginning of the table until a matching protocol name is found, or
  641.     the end of the table is reached.
  642.  
  643.    INPUTS
  644.     name - protocol name
  645.  
  646.    RESULT
  647.     proto (D0) - protocol entry
  648.  
  649. bsdsocket.library/getprotobynumber       bsdsocket.library/getprotobynumber
  650.  
  651.    NAME
  652.     getprotobynumber -- get protocol entry
  653.  
  654.    SYNOPSIS
  655.     proto = getprotobynumber( id );
  656.     D0              D0
  657.  
  658.     struct protoent *getprotobynumber( long id );
  659.  
  660.    FUNCTION
  661.     The getprotobynumber() function returns a pointer to an object which
  662.     represents a network protocol entry in the local network protocol
  663.     data base.  Please see the description of getprotobyname() for more
  664.     information on that structure.
  665.  
  666.    INPUTS
  667.     id - protocol id
  668.  
  669.    RESULT
  670.     proto (D0) - protocol entry
  671.  
  672. bsdsocket.library/getservbyname           bsdsocket.library/getservbyname
  673.  
  674.    NAME
  675.     getservbyname -- get service entry
  676.  
  677.    SYNOPSIS
  678.     serv = getservbyname( name, proto );
  679.     D0              A0    A1
  680.  
  681.     struct servent *getservbyname( char *name, char *proto );
  682.  
  683.    FUNCTION
  684.     The getservbyname() function returns a pointer to an object with the
  685.     following structure containing the broken-out fields of an entry in
  686.     the local network services data base.
  687.  
  688.      struct  servent {
  689.        char    *s_name;       /* official name of service */
  690.        char    **s_aliases;    /* alias list */
  691.        int       s_port;       /* port service resides at */
  692.        char    *s_proto;       /* protocol to use */
  693.      };
  694.  
  695.     The members of this structure are:
  696.  
  697.     s_name The official name of the service.
  698.  
  699.     s_aliases A zero terminated list of alternate names for the service.
  700.  
  701.     s_port The port number at which the service resides.  Port numbers
  702.     are returned in network byte order.
  703.  
  704.     s_proto The name of the protocol to use when contacting the service.
  705.  
  706.     The getservbyname() function sequentially searches from the beginning
  707.     of the table until a matching protocol name or port number is found,
  708.     or until the end of the table has been reached.  If a protocol name
  709.     is also supplied (non-NULL), searches must also match the protocol.
  710.  
  711.    INPUTS
  712.     name - service name
  713.  
  714.     proto - protocol name
  715.  
  716.    RESULT
  717.     serv (D0) - service entry
  718.  
  719. bsdsocket.library/getservbyport           bsdsocket.library/getservbyport
  720.  
  721.    NAME
  722.     getservbyport -- get service entry
  723.  
  724.    SYNOPSIS
  725.     serv = getservbyport( port, proto );
  726.     D0              D0    A0
  727.  
  728.     struct servent *getservbyport( long port, const unsigned char *proto
  729.         );
  730.  
  731.    FUNCTION
  732.     The getservbyport() function returns a pointer to an object which
  733.     represents a network service entry in the local network services data
  734.     base.  Please see the description of getservbyname() for more
  735.     information on that structure.
  736.  
  737.    INPUTS
  738.     port - port number
  739.  
  740.     proto - protocol name
  741.  
  742.    RESULT
  743.     serv (D0) - service entry
  744.  
  745. bsdsocket.library/GetSocketEvents        bsdsocket.library/GetSocketEvents
  746.  
  747.    NAME
  748.     GetSocketEvents -- get asynchronous socket events
  749.  
  750.    SYNOPSIS
  751.     s  = GetSocketEvents( eventsp );
  752.     D0              A0
  753.  
  754.     long GetSocketEvents( ULONG *eventsp );
  755.  
  756.    FUNCTION
  757.     GetSocketEvents() returns the next asynchronous event for sockets,
  758.     and removes it from the internal queue.  The socket number for which
  759.     the event has occured is returned.  If no asynchronous event is
  760.     pending then -1 is returned.
  761.  
  762.     Applications are notified of asynchronous events through the event
  763.     signal (which has to be set earlier by calling SocketBaseTags() with
  764.     code SBTC_SIGEVENTMASK).
  765.  
  766.     Several different events can occur for each socket.  To enable
  767.     reporting of specific events for a socket call getsockopt() with the
  768.     option SO_EVENTMASK.  After calling GetSocketEvents() the ULONG
  769.     pointed to by eventsp contains the mask of all events that have
  770.     occured for the returned socket.
  771.  
  772.     Possible events:
  773.  
  774.     FD_ACCEPT: A new connection is waiting to be accepted.    The kernel
  775.     keeps track of each pending connection.  If more than one connection
  776.     is pending then the kernel immediately generates a new FD_ACCEPT
  777.     event until all pending connections are accounted for.
  778.  
  779.     FD_CLOSE: The connection was closed.  If it was closed due to an
  780.     error then the FD_ERROR event is set as well.
  781.  
  782.     FD_CONNECT: A pending connection has been established.    This event is
  783.     an indication that a non-blocking connect() has been completed.
  784.  
  785.     FD_ERROR: An asynchronous error has occured.
  786.  
  787.     FD_OOB: New out-of-band data is available for reading.
  788.  
  789.     FD_READ: New data is available for reading.
  790.  
  791.     FD_WRITE: The socket is able to accept data for writing again without
  792.     blocking (only for non-blocking sockets).
  793.  
  794.    INPUTS
  795.     eventsp - pointer to event mask
  796.  
  797.    RESULT
  798.     s (D0) - socket
  799.  
  800. bsdsocket.library/getsockname            bsdsocket.library/getsockname
  801.  
  802.    NAME
  803.     getsockname -- get socket name
  804.  
  805.    SYNOPSIS
  806.     ret = getsockname( s, name, namelen );
  807.     D0           D0 A0    A1
  808.  
  809.     long getsockname( long s, struct sockaddr *name, long *namelen );
  810.  
  811.    FUNCTION
  812.     getsockname() returns the current name for the specified socket.  The
  813.     namelen parameter should be initialized to indicate the amount of
  814.     space pointed to by name.  On return it contains the actual size of
  815.     the name returned (in bytes).
  816.  
  817.     A 0 is returned if the call succeeds, -1 if it fails.
  818.  
  819.     The call succeeds unless:
  820.  
  821.     [EBADF] The argument s is not a valid descriptor.
  822.  
  823.     [ENOBUFS] Insufficient resources were available in the system to
  824.     perform the operation.
  825.  
  826.    INPUTS
  827.     s - socket
  828.  
  829.     name - name (address) buffer
  830.  
  831.     namelen - size of name buffer
  832.  
  833.    RESULT
  834.     ret (D0) - return code
  835.  
  836. bsdsocket.library/getsockopt             bsdsocket.library/getsockopt
  837.  
  838.    NAME
  839.     getsockopt -- get options on sockets
  840.  
  841.    SYNOPSIS
  842.     ret = getsockopt( s, level, optname, optval, optlen );
  843.     D0          D0 D1     D2         A0      A1
  844.  
  845.     long getsockopt( long s, long level, long optname, void *optval, long
  846.         *optlen );
  847.  
  848.    FUNCTION
  849.     getsockopt() returns the options associated with a socket.  Options
  850.     may exist at multiple protocol levels; they are always present at the
  851.     uppermost ``socket'' level.
  852.  
  853.     When manipulating socket options the level at which the option
  854.     resides and the name of the option must be specified.  To manipulate
  855.     options at the socket level, level is specified as SOL_SOCKET.    To
  856.     manipulate options at any other level the protocol number of the
  857.     appropriate protocol controlling the option is supplied.  For
  858.     example, to indicate that an option is to be interpreted by the TCP
  859.     protocol, level should be set to the protocol number of TCP; see
  860.     getprotoent().
  861.  
  862.     The parameters optval and optlen are used to access option values for
  863.     setsockopt().  For getsockopt() they identify a buffer in which the
  864.     value for the requested option(s) are to be returned.  For
  865.     getsockopt(), optlen is a value-result parameter, initially
  866.     containing the size of the buffer pointed to by optval, and modified
  867.     on return to indicate the actual size of the value returned.  If no
  868.     option value is to be supplied or returned, optval may be NULL.
  869.  
  870.     Optname and any specified options are passed uninterpreted to the
  871.     appropriate protocol module for interpretation.  The include file
  872.     <sys/socket.h> contains definitions for socket level options,
  873.     described below.  Options at other protocol levels vary in format and
  874.     name.
  875.  
  876.     Most socket-level options utilize a long parameter for optval.    For
  877.     setsockopt(), the parameter should be non-zero to enable a boolean
  878.     option, or zero if the option is to be disabled.  SO_LINGER uses a
  879.     struct linger parameter, defined in <sys/socket.h>, which specifies
  880.     the desired state of the option and the linger interval (see below).
  881.     SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval parameter, defined
  882.     in <sys/time.h>.
  883.  
  884.     The following options are recognized at the socket level.  Except as
  885.     noted, each may be examined with getsockopt() and set with
  886.     setsockopt().
  887.  
  888.     SO_DEBUG    enables recording of debugging information (not
  889.             functional in all protocol stacks)
  890.     SO_REUSEADDR    enables local address reuse
  891.     SO_REUSEPORT    enables duplicate address and port bindings
  892.     SO_KEEPALIVE    enables keep connections alive
  893.     SO_DONTROUTE    enables routing bypass for outgoing messages
  894.     SO_LINGER    linger on close if data present
  895.     SO_BROADCAST    enables permission to transmit broadcast messages
  896.     SO_OOBINLINE    enables reception of out-of-band data in band
  897.     SO_SNDBUF    set buffer size for output
  898.     SO_RCVBUF    set buffer size for input
  899.     SO_RCVBUF    set buffer size for input
  900.     SO_SNDLOWAT    set minimum count for output
  901.     SO_RCVLOWAT    set minimum count for input
  902.     SO_SNDTIMEO    set timeout value for output
  903.     SO_RCVTIMEO    set timeout value for input
  904.     SO_TYPE     get the type of the socket (get only)
  905.     SO_ERROR    get and clear error on the socket (get only)
  906.     SO_EVENTMASK    set the event mask for asynchronous notification
  907.  
  908.     SO_DEBUG enables debugging in the underlying protocol modules.
  909.     SO_REUSEADDR indicates that the rules used in validating addresses
  910.     supplied in a bind() call should allow reuse of local addresses.
  911.     SO_REUSEPORT allows completely duplicate bindings by multiple
  912.     processes if they all set SO_REUSEPORT before binding the port.  This
  913.     option permits multiple instances of a program to each receive UDP/IP
  914.     multicast or broadcast datagrams destined for the bound port.
  915.     SO_KEEPALIVE enables the periodic transmission of messages on a
  916.     connected socket.  Should the connected party fail to respond to
  917.     these messages, the connection is considered broken and processes
  918.     using the socket receive an error indication when attempting to send
  919.     data.  SO_DONTROUTE indicates that outgoing messages should bypass
  920.     the standard routing facilities.  Instead, messages are directed to
  921.     the appropriate network interface according to the network portion of
  922.     the destination address.
  923.  
  924.     SO_LINGER controls the action taken when unsent messages are queued
  925.     on socket and a close() is performed.  If the socket promises
  926.     reliable delivery of data and SO_LINGER is set, the system will block
  927.     the process on the close attempt until it is able to transmit the
  928.     data or until it decides it is unable to deliver the information (a
  929.     timeout period, termed the linger interval, is specified in seconds
  930.     in the setsockopt() call when SO_LINGER is requested).    If SO_LINGER
  931.     is disabled and a close is issued, the system will process the close
  932.     in a manner that allows the process to continue as quickly as
  933.     possible.
  934.  
  935.     The option SO_BROADCAST requests permission to send broadcast
  936.     datagrams on the socket.  With protocols that support out-of-band
  937.     data, the SO_OOBINLINE option requests that out-of-band data be
  938.     placed in the normal data input queue as received; it will then be
  939.     accessible with recv calls without the MSG_OOB flag.  Some protocols
  940.     always behave as if this option is set.  SO_SNDBUF and SO_RCVBUF are
  941.     options to adjust the normal buffer sizes allocated for output and
  942.     input buffers, respectively.  The buffer size may be increased for
  943.     high-volume connections, or may be decreased to limit the possible
  944.     backlog of incoming data.  The system places an absolute limit on
  945.     these values.
  946.  
  947.     SO_SNDLOWAT is an option to set the minimum count for output
  948.     operations.  Most output operations process all of the data supplied
  949.     by the call, delivering data to the protocol for transmission and
  950.     blocking as necessary for flow control.  Nonblocking output
  951.     operations will process as much data as permitted subject to flow
  952.     control without blocking, but will process no data if flow control
  953.     does not allow the smaller of the low water mark value or the entire
  954.     request to be processed.  A select() operation testing the ability to
  955.     write to a socket will return true only if the low water mark amount
  956.     could be processed.  The default value for SO_SNDLOWAT is set to a
  957.     convenient size for network efficiency, often 1024.  SO_RCVLOWAT is
  958.     an option to set the minimum count for input operations.  In general,
  959.     receive calls will block until any (non-zero) amount of data is
  960.     received, then return with the smaller of the amount available or the
  961.     amount requested.  The default value for SO_RCVLOWAT is 1.  If
  962.     SO_RCVLOWAT is set to a larger value, blocking receive calls normally
  963.     wait until they have received the smaller of the low water mark value
  964.     or the requested amount.  Receive calls may still return less than
  965.     the low water mark if an error occurs, a signal is caught, or the
  966.     type of data next in the receive queue is different than that
  967.     returned.
  968.  
  969.     SO_SNDTIMEO is an option to set a timeout value for output
  970.     operations.  It accepts a struct timeval parameter with the number of
  971.     seconds and microseconds used to limit waits for output operations to
  972.     complete.  If a send operation has blocked for this much time, it
  973.     returns with a partial count or with the error EWOULDBLOCK if no data
  974.     were sent.  In the current implementation, this timer is restarted
  975.     each time additional data are delivered to the protocol, implying
  976.     that the limit applies to output portions ranging in size from the
  977.     low water mark to the high water mark for output.  SO_RCVTIMEO is an
  978.     option to set a timeout value for input operations.  It accepts a
  979.     struct timeval parameter with the number of seconds and microseconds
  980.     used to limit waits for input operations to complete.  In the current
  981.     implementation, this timer is restarted each time additional data are
  982.     received by the protocol, and thus the limit is in effect an
  983.     inactivity timer.  If a receive operation has been blocked for this
  984.     much time without receiving additional data, it returns with a short
  985.     count or with the error EWOULDBLOCK if no data were received.
  986.  
  987.     SO_EVENTMASK defines the bitmask of asynchronous events which are
  988.     supposed to trigger a notification and can later be retrieved by
  989.     calling GetSocketEvents.
  990.  
  991.     Finally, SO_TYPE and SO_ERROR are options used only with
  992.     getsockopt().  SO_TYPE returns the type of the socket, such as
  993.     SOCK_STREAM; it is useful for servers that inherit sockets on
  994.     startup.  SO_ERROR returns any pending error on the socket and clears
  995.     the error status.  It may be used to check for asynchronous errors on
  996.     connected datagram sockets or for other asynchronous errors.
  997.  
  998.     A 0 is returned if the call succeeds, -1 if it fails.
  999.  
  1000.     The call succeeds unless:
  1001.  
  1002.     [EBADF] The argument s is not a valid descriptor.
  1003.  
  1004.     [ENOPROTOOPT] The option is unknown at the level indicated.
  1005.  
  1006.    INPUTS
  1007.     s - socket
  1008.  
  1009.     level - socket level
  1010.  
  1011.     optname - option name
  1012.  
  1013.     optval - option value
  1014.  
  1015.     optlen - length of option value
  1016.  
  1017.    RESULT
  1018.     ret (D0) - return code
  1019.  
  1020. bsdsocket.library/inet_addr              bsdsocket.library/inet_addr
  1021.  
  1022.    NAME
  1023.     inet_addr -- convert IP address from text to binary form
  1024.  
  1025.    SYNOPSIS
  1026.     ip = inet_addr( cp );
  1027.     D0        A0
  1028.  
  1029.     unsigned long inet_addr( char *cp );
  1030.  
  1031.    FUNCTION
  1032.     The routine inet_addr() interprets character strings representing
  1033.     numbers expressed in the Internet standard `.' notation.  It returns
  1034.     numbers suitable for use as Internet addresses.
  1035.  
  1036.     All Internet addresses are returned in network order (bytes ordered
  1037.     from left to right).  All network numbers and local address parts are
  1038.     returned as machine format integer values.
  1039.  
  1040.     INTERNET ADDRESSES Values specified using the `.' notation take one
  1041.     of the following forms:
  1042.  
  1043.     a.b.c.d a.b.c a.b a
  1044.  
  1045.     When four parts are specified, each is interpreted as a byte of data
  1046.     and assigned, from left to right, to the four bytes of an Internet
  1047.     address.
  1048.  
  1049.     When a three part address is specified, the last part is interpreted
  1050.     as a 16-bit quantity and placed in the right-most two bytes of the
  1051.     network address.  This makes the three part address format convenient
  1052.     for specifying Class B network addresses as ``128.net.host''.
  1053.  
  1054.     When a two part address is supplied, the last part is interpreted as
  1055.     a 24-bit quantity and placed in the right most three bytes of the
  1056.     network address.  This makes the two part address format convenient
  1057.     for specifying Class A network addresses as ``net.host''.
  1058.  
  1059.     When only one part is given, the value is stored directly in the
  1060.     network address without any byte rearrangement.
  1061.  
  1062.     All numbers supplied as ``parts'' in a `.' notation may be decimal,
  1063.     octal, or hexadecimal, as specified in the C language (i.e., a
  1064.     leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies
  1065.     octal; otherwise, the number is interpreted as decimal).
  1066.  
  1067.     The constant INADDR_NONE is returned by inet_addr() and
  1068.     inet_network() for malformed requests.
  1069.  
  1070.    INPUTS
  1071.     cp - text string
  1072.  
  1073.    RESULT
  1074.     ip (D0) - ip address
  1075.  
  1076. bsdsocket.library/inet_lnaof             bsdsocket.library/inet_lnaof
  1077.  
  1078.    NAME
  1079.     inet_lnaof -- return host part of IP address
  1080.  
  1081.    SYNOPSIS
  1082.     ip = inet_lnaof( in    );
  1083.     D0         stack
  1084.  
  1085.     unsigned long inet_lnaof( struct in_addr in );
  1086.  
  1087.    FUNCTION
  1088.     This function is identical to Inet_LnaOf(), except that its argument
  1089.     is a structure containing the IP address (instead of accepting the IP
  1090.     address in an unsigned long).  Because of that no pragma call for
  1091.     inet_lnaof() exists.
  1092.  
  1093.     This function has been deprecated, because it depends on an obsolete
  1094.     fixed Internet addressing scheme, and does not take subnetting or
  1095.     supernetting into account.
  1096.  
  1097.     For more information on IP addresses and error conditions please see
  1098.     the documentation for inet_addr().
  1099.  
  1100.    INPUTS
  1101.     in - ip address
  1102.  
  1103.    RESULT
  1104.     ip (D0) - host part
  1105.  
  1106. bsdsocket.library/Inet_LnaOf             bsdsocket.library/Inet_LnaOf
  1107.  
  1108.    NAME
  1109.     Inet_LnaOf -- return host part of IP address
  1110.  
  1111.    SYNOPSIS
  1112.     ip = Inet_LnaOf( in );
  1113.     D0         D0
  1114.  
  1115.     unsigned long Inet_LnaOf( unsigned long in );
  1116.  
  1117.    FUNCTION
  1118.     The routine Inet_LnaOf() breaks apart Internet host addresses
  1119.     returning only the local network address part.
  1120.  
  1121.     This function has been deprecated, because it depends on an obsolete
  1122.     fixed Internet addressing scheme, and does not take subnetting or
  1123.     supernetting into account.
  1124.  
  1125.     For more information on IP addresses and error conditions please see
  1126.     the documentation for inet_addr().
  1127.  
  1128.    INPUTS
  1129.     in - ip address
  1130.  
  1131.    RESULT
  1132.     ip (D0) - host part
  1133.  
  1134. bsdsocket.library/inet_makeaddr           bsdsocket.library/inet_makeaddr
  1135.  
  1136.    NAME
  1137.     inet_makeaddr -- create IP address from network number and host
  1138.     number
  1139.  
  1140.    SYNOPSIS
  1141.     ip    = inet_makeaddr( net, host );
  1142.     stack               D0   D1
  1143.  
  1144.     struct in_addr inet_makeaddr( unsigned long net, unsigned long host
  1145.         );
  1146.  
  1147.    FUNCTION
  1148.     This function is identical to Inet_MakeAddr(), except that its result
  1149.     is returned in a structure, not in an unsigned long.  Because of that
  1150.     no pragma call for inet_makeaddr() exists.
  1151.  
  1152.     This function has been deprecated, because it depends on an obsolete
  1153.     fixed Internet addressing scheme, and does not take subnetting or
  1154.     supernetting into account.
  1155.  
  1156.     For more information on IP addresses and error conditions please see
  1157.     the documentation for inet_addr().
  1158.  
  1159.    INPUTS
  1160.     net - network number
  1161.  
  1162.     host - host number
  1163.  
  1164.    RESULT
  1165.     ip (stack) - ip address
  1166.  
  1167. bsdsocket.library/Inet_MakeAddr           bsdsocket.library/Inet_MakeAddr
  1168.  
  1169.    NAME
  1170.     Inet_MakeAddr -- create IP address from network number and host
  1171.     number
  1172.  
  1173.    SYNOPSIS
  1174.     ip = Inet_MakeAddr( net, host );
  1175.     D0            D0     D1
  1176.  
  1177.     unsigned long Inet_MakeAddr( unsigned long net, unsigned long host );
  1178.  
  1179.    FUNCTION
  1180.     This function takes an Internet network number and a local network
  1181.     address and constructs an Internet address from it.
  1182.  
  1183.     This function has been deprecated, because it depends on an obsolete
  1184.     fixed Internet addressing scheme, and does not take subnetting or
  1185.     supernetting into account.
  1186.  
  1187.     For more information on IP addresses and error conditions please see
  1188.     the documentation for inet_addr().
  1189.  
  1190.    INPUTS
  1191.     net - network number
  1192.  
  1193.     host - host number
  1194.  
  1195.    RESULT
  1196.     ip (D0) - ip address
  1197.  
  1198. bsdsocket.library/inet_netof             bsdsocket.library/inet_netof
  1199.  
  1200.    NAME
  1201.     inet_netof -- return network part of IP address
  1202.  
  1203.    SYNOPSIS
  1204.     ip = inet_netof( in    );
  1205.     D0         stack
  1206.  
  1207.     unsigned long inet_netof( struct in_addr in );
  1208.  
  1209.    FUNCTION
  1210.     This function is identical to Inet_NetOf(), except that its argument
  1211.     is a structure containing the IP address (instead of accepting the IP
  1212.     address in an unsigned long).  Because of that no pragma call for
  1213.     inet_netof() exists.
  1214.  
  1215.     This function has been deprecated, because it depends on an obsolete
  1216.     fixed Internet addressing scheme, and does not take subnetting or
  1217.     supernetting into account.
  1218.  
  1219.     For more information on IP addresses and error conditions please see
  1220.     the documentation for inet_addr().
  1221.  
  1222.    INPUTS
  1223.     in - ip address
  1224.  
  1225.    RESULT
  1226.     ip (D0) - network part
  1227.  
  1228. bsdsocket.library/Inet_NetOf             bsdsocket.library/Inet_NetOf
  1229.  
  1230.    NAME
  1231.     Inet_NetOf -- return network part of IP address
  1232.  
  1233.    SYNOPSIS
  1234.     ip = Inet_NetOf( in );
  1235.     D0         D0
  1236.  
  1237.     unsigned long Inet_NetOf( unsigned long in );
  1238.  
  1239.    FUNCTION
  1240.     The routine Inet_NetOf() breaks apart Internet host addresses
  1241.     returning only the network number.
  1242.  
  1243.     This function has been deprecated, because it depends on an obsolete
  1244.     fixed Internet addressing scheme, and does not take subnetting or
  1245.     supernetting into account.
  1246.  
  1247.     For more information on IP addresses and error conditions please see
  1248.     the documentation for inet_addr().
  1249.  
  1250.    INPUTS
  1251.     in - ip address
  1252.  
  1253.    RESULT
  1254.     ip (D0) - network part
  1255.  
  1256. bsdsocket.library/inet_network               bsdsocket.library/inet_network
  1257.  
  1258.    NAME
  1259.     inet_network -- convert network number from text to binary form
  1260.  
  1261.    SYNOPSIS
  1262.     net = inet_network( cp );
  1263.     D0            A0
  1264.  
  1265.     unsigned long inet_network( char *cp );
  1266.  
  1267.    FUNCTION
  1268.     The routine inet_addr() interprets character strings representing
  1269.     numbers expressed in the Internet standard `.' notation.  It returns
  1270.     numbers suitable for use as Internet network numbers.
  1271.  
  1272.     This function has been deprecated, because it depends on an obsolete
  1273.     fixed Internet addressing scheme, and does not take subnetting or
  1274.     supernetting into account.
  1275.  
  1276.     For more information on IP addresses and error conditions please see
  1277.     the documentation for inet_addr().
  1278.  
  1279.    INPUTS
  1280.     cp - text string
  1281.  
  1282.    RESULT
  1283.     net (D0) - network number
  1284.  
  1285. bsdsocket.library/inet_ntoa              bsdsocket.library/inet_ntoa
  1286.  
  1287.    NAME
  1288.     inet_ntoa -- convert IP address from binary to text form
  1289.  
  1290.    SYNOPSIS
  1291.     cp = inet_ntoa( ip    );
  1292.     D0        stack
  1293.  
  1294.     char *inet_ntoa( struct in_addr ip );
  1295.  
  1296.    FUNCTION
  1297.     This function is identical to Inet_NtoA(), except that its argument
  1298.     is a structure containing the IP address (instead of accepting the IP
  1299.     address in an unsigned long).  Because of that no pragma call for
  1300.     inet_ntoa() exists.
  1301.  
  1302.     For more information on IP addresses and error conditions please see
  1303.     the documentation for inet_addr().
  1304.  
  1305.    INPUTS
  1306.     ip - ip address
  1307.  
  1308.    RESULT
  1309.     cp (D0) - text string
  1310.  
  1311. bsdsocket.library/Inet_NtoA              bsdsocket.library/Inet_NtoA
  1312.  
  1313.    NAME
  1314.     Inet_NtoA -- convert IP address from binary to text form
  1315.  
  1316.    SYNOPSIS
  1317.     cp = Inet_NtoA( ip );
  1318.     D0        D0
  1319.  
  1320.     char *Inet_NtoA( unsigned long ip );
  1321.  
  1322.    FUNCTION
  1323.     The routine inet_ntoa() takes an Internet address and returns an
  1324.     ASCII string representing the address in `.' notation.
  1325.  
  1326.     For more information on IP addresses and error conditions please see
  1327.     the documentation for inet_addr().
  1328.  
  1329.    INPUTS
  1330.     ip - ip address
  1331.  
  1332.    RESULT
  1333.     cp (D0) - text string
  1334.  
  1335. bsdsocket.library/IoctlSocket            bsdsocket.library/IoctlSocket
  1336.  
  1337.    NAME
  1338.     IoctlSocket -- control socket parameters
  1339.  
  1340.    SYNOPSIS
  1341.     ret = IoctlSocket( s, req, argp );
  1342.     D0           D0 D0   A0
  1343.  
  1344.     long IoctlSocket( long s, unsigned long req, char *argp );
  1345.  
  1346.    FUNCTION
  1347.     The IoctlSocket() function manipulates the socket parameters of the
  1348.     specified socket.  The argument s must be an valid socket descriptor.
  1349.  
  1350.     An ioctl request has encoded in it whether the argument is an ``in''
  1351.     parameter or ``out'' parameter, and the size of the argument argp in
  1352.     bytes.    Macros and defines used in specifying an ioctl request are
  1353.     located in the file <sys/ioctl.h>.
  1354.  
  1355.     The supported requests are:
  1356.  
  1357.     FIOASYNC: The argument is of type (long *).  Setting the value to 1
  1358.     enables asynchronous I/O on the socket.  Setting the value to 0
  1359.     disables asynchronous I/O on the socket.
  1360.  
  1361.     FIOGETOWN, SIOCGPGRP: The argument is of type (struct Task **).  The
  1362.     kernel sets the value pointed to to the task that receives
  1363.     notification events for the socket.
  1364.  
  1365.     FIOSETOWN, SIOCSPGRP: The argument is of type (struct Task **).  This
  1366.     option defines which task will receive notification events for the
  1367.     socket.
  1368.  
  1369.     FIONBIO: The argument is of type (long *).  Setting the value to 1
  1370.     sets the socket to non-blocking I/O.  Setting the value to 0 sets the
  1371.     socket to blocking I/O.
  1372.  
  1373.     FIONREAD: The argument is of type (long *).  The kernel sets the
  1374.     value pointed to to the number of readable characters on the socket.
  1375.  
  1376.     SIOCCATMARK: The argument is of type (long *).    The kernel sets the
  1377.     value pointed to to 1 if the read pointer for the socket points to a
  1378.     mark in the data stream, and to 0 if the read pointer for the socket
  1379.     does not point to a mark.
  1380.  
  1381.     If an error has occurred, a value of -1 is returned and the return
  1382.     value of Errno() indicates the error.
  1383.  
  1384.     IoctlSocket() will fail if:
  1385.  
  1386.     [EBADF] s is not a valid descriptor.
  1387.  
  1388.     [EINVAL] Request or argp is not valid.
  1389.  
  1390.    INPUTS
  1391.     s - socket descriptor
  1392.  
  1393.     req - request
  1394.  
  1395.     argp - arguments
  1396.  
  1397.    RESULT
  1398.     ret (D0) - return code
  1399.  
  1400. bsdsocket.library/listen                 bsdsocket.library/listen
  1401.  
  1402.    NAME
  1403.     listen -- listen for connections on a socket
  1404.  
  1405.    SYNOPSIS
  1406.     ret = listen( s, backlog );
  1407.     D0          D0 D1
  1408.  
  1409.     long listen( long s, long backlog );
  1410.  
  1411.    FUNCTION
  1412.     To accept connections, a socket is first created with socket(), a
  1413.     willingness to accept incoming connections and a queue limit for
  1414.     incoming connections are specified with listen(), and then the
  1415.     connections are accepted with accept().  The listen() call applies
  1416.     only to sockets of type SOCK_STREAM or SOCK_SEQPACKET.
  1417.  
  1418.     The backlog parameter defines the maximum length the queue of pending
  1419.     connections may grow to.  If a connection request arrives with the
  1420.     queue full the client may receive an error with an indication of
  1421.     ECONNREFUSED, or, if the underlying protocol supports retransmission,
  1422.     the request may be ignored so that retries may succeed.
  1423.  
  1424.     The backlog parameter does not directly specify the maximum length of
  1425.     the backlog queue, but instead specifies an index into a table for
  1426.     the maximum length.  Currently the backlog parameter is limited to
  1427.     values from 1 to 5, and the translation table looks as follows:
  1428.  
  1429.     backlog parameter   maximum length
  1430.            1           1
  1431.            2           3
  1432.            3           4
  1433.            4           6
  1434.            5           variable, default=7
  1435.  
  1436.     In Miami the maximum length for a backlog parameter of 5 can be
  1437.     changed by the system administrator by modifying the entity
  1438.     'socket.maxqlen' through MiamiSysCtl.
  1439.  
  1440.     A 0 return value indicates success; -1 indicates an error.
  1441.  
  1442.     listen() will fail if:
  1443.  
  1444.     [EBADF] The argument s is not a valid descriptor.
  1445.  
  1446.     [EOPNOTSUPP] The socket is not of a type that supports the operation
  1447.     listen().
  1448.  
  1449.    INPUTS
  1450.     s - socket
  1451.  
  1452.     backlog - listen backlog
  1453.  
  1454.    RESULT
  1455.     ret (D0) - return code
  1456.  
  1457. bsdsocket.library/ObtainSocket               bsdsocket.library/ObtainSocket
  1458.  
  1459.    NAME
  1460.     ObtainSocket -- obtain a previously released socket
  1461.  
  1462.    SYNOPSIS
  1463.     s  = ObtainSocket( id, domain, type, protocol );
  1464.     D0           D0  D1      D2    D3
  1465.  
  1466.     long ObtainSocket( long id, long domain, long type, long protocol );
  1467.  
  1468.    FUNCTION
  1469.     This function gives a task control over a socket which was previously
  1470.     released to the public socket list by some other task (by calling
  1471.     ReleaseSocket() or ReleaseCopyOfSocket()).  The primary use of this
  1472.     function is to pass a socket from InetD to a daemon.
  1473.  
  1474.     "id" is the "key" value returned by ReleaseSocket() or
  1475.     ReleaseCopyOfSocket().    The other parameters can be used to further
  1476.     narrow down the set of sockets.  A value of 0 for domain indicates
  1477.     that a socket in any domain is acceptable.
  1478.  
  1479.     The socket number of the socket is returned on success.  If an error
  1480.     has occured -1 is returned.
  1481.  
  1482.    INPUTS
  1483.     id - socket id
  1484.  
  1485.     domain - domain
  1486.  
  1487.     type - socket type
  1488.  
  1489.     protocol - protocol
  1490.  
  1491.    RESULT
  1492.     s (D0) - socket
  1493.  
  1494. bsdsocket.library/recv                       bsdsocket.library/recv
  1495.  
  1496.    NAME
  1497.     recv -- receive data from a socket
  1498.  
  1499.    SYNOPSIS
  1500.     recvlen = recv( s, buf, len, flags );
  1501.     D0        D0 A0    D1   D2
  1502.  
  1503.     long recv( long s, unsigned char *buf, long len, long flags );
  1504.  
  1505.    FUNCTION
  1506.     The recv() call is normally used only on a connected socket (see
  1507.     connect()) and is identical to recvfrom() with a nil from parameter.
  1508.     As it is redundant, it may not be supported in future releases.
  1509.  
  1510.     recv() returns the length of the message on successful completion.
  1511.     If a message is too long to fit in the supplied buffer, excess bytes
  1512.     may be discarded depending on the type of socket the message is
  1513.     received from (see socket()).
  1514.  
  1515.     If no messages are available at the socket, the receive call waits
  1516.     for a message to arrive, unless the socket is nonblocking (see
  1517.     IoctlSocket()) in which case the value -1 is returned and the
  1518.     function Errno() returns EAGAIN.  The receive calls normally return
  1519.     any data available, up to the requested amount, rather than waiting
  1520.     for receipt of the full amount requested; this behavior is affected
  1521.     by the socket-level options SO_RCVLOWAT and SO_RCVTIMEO described in
  1522.     getsockopt().
  1523.  
  1524.     The select() call may be used to determine when more data arrive.
  1525.  
  1526.     The flags argument to a recv call is formed by oring one or more of
  1527.     the values:
  1528.  
  1529.          MSG_OOB        process out-of-band data
  1530.          MSG_PEEK        peek at incoming message
  1531.          MSG_WAITALL    wait for full request or error
  1532.     The MSG_OOB flag requests receipt of out-of-band data that would not
  1533.     be received in the normal data stream.    Some protocols place
  1534.     expedited data at the head of the normal data queue, and thus this
  1535.     flag cannot be used with such protocols.  The MSG_PEEK flag causes
  1536.     the receive operation to return data from the beginning of the
  1537.     receive queue without removing that data from the queue.  Thus, a
  1538.     subsequent receive call will return the same data.  The MSG_WAITALL
  1539.     flag requests that the operation block until the full request is
  1540.     satisfied.  However, the call may still return less data than
  1541.     requested if a signal is caught, an error or disconnect occurs, or
  1542.     the next data to be received is of a different type than that
  1543.     returned.
  1544.  
  1545.     The call returns the number of bytes received, or -1 if an error
  1546.     occurred.
  1547.  
  1548.     The call fails if:
  1549.  
  1550.     [EBADF] The argument s is an invalid descriptor.
  1551.  
  1552.     [ENOTCONN] The socket is associated with a connection-oriented
  1553.     protocol and has not been connected (see connect() and accept()).
  1554.  
  1555.     [EAGAIN] The socket is marked non-blocking, and the receive operation
  1556.     would block, or a receive timeout had been set, and the timeout
  1557.     expired before data were received.
  1558.  
  1559.     [EINTR] The receive was interrupted by delivery of a signal before
  1560.     any data were available.
  1561.  
  1562.    INPUTS
  1563.     s - socket
  1564.  
  1565.     buf - buffer
  1566.  
  1567.     len - length
  1568.  
  1569.     flags - flags
  1570.  
  1571.    RESULT
  1572.     recvlen (D0) - length received
  1573.  
  1574. bsdsocket.library/recvfrom               bsdsocket.library/recvfrom
  1575.  
  1576.    NAME
  1577.     recvfrom -- receive data from a socket
  1578.  
  1579.    SYNOPSIS
  1580.     recvlen = recvfrom( s, buf, len, flags, addr, addrlen );
  1581.     D0            D0 A0   D1     D2    A1    A2
  1582.  
  1583.     long recvfrom( long s, unsigned char *buf, long len, long flags,
  1584.         struct sockaddr *addr, long *addrlen );
  1585.  
  1586.    FUNCTION
  1587.     recvfrom() is used to receive messages from a socket, and may be used
  1588.     to receive data on a socket whether or not it is connection-oriented.
  1589.  
  1590.     If from is non-nil, and the socket is not connection-oriented, the
  1591.     source address of the message is filled in.  Fromlen is a
  1592.     value-result parameter, initialized to the size of the buffer
  1593.     associated with from, and modified on return to indicate the actual
  1594.     size of the address stored there.
  1595.  
  1596.     For more information please see the description of recv().
  1597.  
  1598.    INPUTS
  1599.     s - socket
  1600.  
  1601.     buf - buffer
  1602.  
  1603.     len - length
  1604.  
  1605.     flags - flags
  1606.  
  1607.     addr - address
  1608.  
  1609.     addrlen - address length
  1610.  
  1611.    RESULT
  1612.     recvlen (D0) - length received
  1613.  
  1614. bsdsocket.library/recvmsg                bsdsocket.library/recvmsg
  1615.  
  1616.    NAME
  1617.     recvmsg -- receive data from a socket
  1618.  
  1619.    SYNOPSIS
  1620.     recvlen = recvmsg( s, msg, flags );
  1621.     D0           D0 A0   D1
  1622.  
  1623.     long recvmsg( long s, struct msghdr *msg, long flags );
  1624.  
  1625.    FUNCTION
  1626.     recvmsg() is used to receive messages from a socket, and may be used
  1627.     to receive data on a socket whether or not it is connection-oriented.
  1628.  
  1629.     The recvmsg() call uses a msghdr structure to minimize the number of
  1630.     directly supplied parameters.  This structure has the following form,
  1631.     as defined in <sys/socket.h>:
  1632.  
  1633.     struct msghdr {
  1634.        caddr_t msg_name;       /* optional address */
  1635.        u_int   msg_namelen;    /* size of address */
  1636.        struct  iovec *msg_iov; /* scatter/gather array */
  1637.        u_int   msg_iovlen;       /* # elements in msg_iov */
  1638.        caddr_t msg_control;    /* ancillary data, see below */
  1639.        u_int   msg_controllen; /* ancillary data buffer len */
  1640.        int       msg_flags;       /* flags on received message */
  1641.     };
  1642.  
  1643.     Here msg_name and msg_namelen specify the destination address if the
  1644.     socket is unconnected; msg_name may be given as a null pointer if no
  1645.     names are desired or required.    msg_iov and msg_iovlen describe
  1646.     scatter gather locations.  msg_control, which has length
  1647.     msg_controllen, points to a buffer for other protocol control related
  1648.     messages or other miscellaneous ancillary data.  The messages are of
  1649.     the form:
  1650.  
  1651.     struct cmsghdr {
  1652.        u_int   cmsg_len;       /* data byte count, including hdr */
  1653.        int       cmsg_level;       /* originating protocol */
  1654.        int       cmsg_type;       /* protocol-specific type */
  1655.     /* followed by
  1656.        u_char  cmsg_data[]; */
  1657.     };
  1658.  
  1659.     The msg_flags field is set on return according to the message
  1660.     received.  MSG_EOR indicates end-of-record; the data returned
  1661.     completed a record (generally used with sockets of type
  1662.     SOCK_SEQPACKET).  MSG_TRUNC indicates that the trailing portion of a
  1663.     datagram was discarded because the datagram was larger than the
  1664.     buffer supplied.  MSG_CTRUNC indicates that some control data were
  1665.     discarded due to lack of space in the buffer for ancillary data.
  1666.     MSG_OOB is returned to indicate that expedited or out-of-band data
  1667.     were received.
  1668.  
  1669.     For more information please see the description of recv().
  1670.  
  1671.    INPUTS
  1672.     s - socket
  1673.  
  1674.     msg - message header
  1675.  
  1676.     flags - flags
  1677.  
  1678.    RESULT
  1679.     recvlen (D0) - length received
  1680.  
  1681. bsdsocket.library/ReleaseCopyOfSocket    bsdsocket.library/ReleaseCopyOfSocket
  1682.  
  1683.    NAME
  1684.     ReleaseCopyOfSocket -- release a copy of a socket to the public
  1685.     socket pool
  1686.  
  1687.    SYNOPSIS
  1688.     key = ReleaseCopyOfSocket( s, id );
  1689.     D0               D0 D0
  1690.  
  1691.     long ReleaseCopyOfSocket( long s, long id );
  1692.  
  1693.    FUNCTION
  1694.     ReleaseCopyOfSocket() is identical to ReleaseSocket(), except that
  1695.     the socket is first cloned and that the clone is then released to the
  1696.     public socket list, not the original socket, i.e.  the original
  1697.     socket remains owned by the caller.
  1698.  
  1699.     Please see the documentation on ReleaseSocket() for more details.
  1700.  
  1701.    INPUTS
  1702.     s - socket
  1703.  
  1704.     id - socket id
  1705.  
  1706.    RESULT
  1707.     key (D0) - key value
  1708.  
  1709. bsdsocket.library/ReleaseSocket           bsdsocket.library/ReleaseSocket
  1710.  
  1711.    NAME
  1712.     ReleaseSocket -- release a socket to the public socket pool
  1713.  
  1714.    SYNOPSIS
  1715.     key = ReleaseSocket( s, id );
  1716.     D0             D0 D0
  1717.  
  1718.     long ReleaseSocket( long s, long id );
  1719.  
  1720.    FUNCTION
  1721.     ReleaseSocket() removes a socket from the task's socket list, and
  1722.     releases it to the public socket list, so another task can grab the
  1723.     socket by calling ObtainSocket().
  1724.  
  1725.     The id value can be a non-unique number between 0 and 65535 or a
  1726.     unique number higher than 65535.  It is also possible to have the
  1727.     kernel pick a unique number by passing UNIQUE_ID as the id.
  1728.  
  1729.     The returned value is the key to be used as the first parameter is
  1730.     ObtainSocket(), or -1 if an error has occured.
  1731.  
  1732.    INPUTS
  1733.     s - socket
  1734.  
  1735.     id - socket id
  1736.  
  1737.    RESULT
  1738.     key (D0) - key value
  1739.  
  1740. bsdsocket.library/select                 bsdsocket.library/select
  1741.  
  1742.    NAME
  1743.     select -- synchronous socket I/O multiplexing
  1744.  
  1745.    SYNOPSIS
  1746.     n  = select( nfds, readfds, writefds, exceptfds, timeout );
  1747.     D0         D0    A0        A1          A2     A3
  1748.  
  1749.     long select( long nfds, fd_set *readfds, fd_set *writefds, fd_set
  1750.         *exceptfds, struct timeval *timeout );
  1751.  
  1752.    FUNCTION
  1753.     select() examines the socket descriptor sets whose addresses are
  1754.     passed in readfds, writefds, and exceptfds to see if some of their
  1755.     descriptors are ready for reading, are ready for writing, or have an
  1756.     exceptional condition pending, respectively.  The first nfds
  1757.     descriptors are checked in each set; i.e., the descriptors from 0
  1758.     through nfds-1 in the descriptor sets are examined.  On return,
  1759.     select() replaces the given descriptor sets with subsets consisting
  1760.     of those descriptors that are ready for the requested operation.
  1761.     Select() returns the total number of ready descriptors in all the
  1762.     sets.
  1763.  
  1764.     The descriptor sets are stored as bit fields in arrays of integers.
  1765.     The following macros are provided for manipulating such descriptor
  1766.     sets: FD_ZERO(&fdsetx) initializes a descriptor set fdset to the null
  1767.     set.  FD_SET(fd, &fdset) includes a particular descriptor fd in
  1768.     fdset.    FD_CLR(fd, &fdset) removes fd from fdset.  FD_ISSET(fd,
  1769.     &fdset) is non-zero if fd is a member of fdset, zero otherwise.  The
  1770.     behavior of these macros is undefined if a descriptor value is less
  1771.     than zero or greater than or equal to FD_SETSIZE, which is normally
  1772.     at least equal to the maximum number of descriptors supported by the
  1773.     system.
  1774.  
  1775.     If timeout is a non-nil pointer, it specifies a maximum interval to
  1776.     wait for the selection to complete.  If timeout is a nil pointer, the
  1777.     select blocks indefinitely.  To affect a poll, the timeout argument
  1778.     should be non-nil, pointing to a zero-valued timeval structure.
  1779.  
  1780.     Any of readfds, writefds, and exceptfds may be given as nil pointers
  1781.     if no descriptors are of interest.
  1782.  
  1783.     select() returns the number of ready descriptors that are contained
  1784.     in the descriptor sets, or -1 if an error occurred.  If the time
  1785.     limit expires, select() returns 0.  If select() returns with an
  1786.     error, the descriptor sets will be unmodified.
  1787.  
  1788.     An error return from select() indicates:
  1789.  
  1790.     [EBADF] One of the descriptor sets specified an invalid descriptor.
  1791.  
  1792.     [EINTR] select() was interrupted, usually by Ctrl-C.
  1793.  
  1794.     [EINVAL] The specified time limit is invalid.  One of its components
  1795.     is negative or too large.
  1796.  
  1797.    INPUTS
  1798.     nfds - number of socket descriptors
  1799.  
  1800.     readfds - read fd set
  1801.  
  1802.     writefds - write fd set
  1803.  
  1804.     exceptfds - exception fd set
  1805.  
  1806.     timeout - timeout
  1807.  
  1808.    RESULT
  1809.     n (D0) - numbere of socket descriptors
  1810.  
  1811. bsdsocket.library/send                       bsdsocket.library/send
  1812.  
  1813.    NAME
  1814.     send -- send data to a socket
  1815.  
  1816.    SYNOPSIS
  1817.     sendlen = send( s, buf, len, flags );
  1818.     D0        D0 A0    D1   D2
  1819.  
  1820.     long send( long s, unsigned char *buf, long len, long flags );
  1821.  
  1822.    FUNCTION
  1823.     send() is used to transmit data to another socket.  send() may be
  1824.     used only when the socket is in a connected state.
  1825.  
  1826.     The length of the message is given by len.  If the message is too
  1827.     long to pass atomically through the underlying protocol, the error
  1828.     EMSGSIZE is returned, and the message is not transmitted.
  1829.  
  1830.     No indication of failure to deliver is implicit in a send().  Locally
  1831.     detected errors are indicated by a return value of -1.
  1832.  
  1833.     If no messages space is available at the socket to hold the message
  1834.     to be transmitted, then send() normally blocks, unless the socket has
  1835.     been placed in non-blocking I/O mode.  The select() call may be used
  1836.     to determine when it is possible to send more data.
  1837.  
  1838.     The flags parameter may include one or more of the following:
  1839.  
  1840.     #define MSG_OOB        0x1  /* process out-of-band data */
  1841.     #define MSG_DONTROUTE  0x4  /* bypass routing,
  1842.                        use direct interface */
  1843.  
  1844.     The flag MSG_OOB is used to send ``out-of-band'' data on sockets that
  1845.     support this notion (e.g.  SOCK_STREAM); the underlying protocol must
  1846.     also support ``out-of-band'' data.  MSG_DONTROUTE is usually used
  1847.     only by diagnostic or routing programs.
  1848.  
  1849.     See recv() for a description of the msghdr structure.
  1850.  
  1851.     The call returns the number of characters sent, or -1 if an error
  1852.     occurred.
  1853.  
  1854.     send() fails if:
  1855.  
  1856.     [EBADF] An invalid descriptor was specified.
  1857.  
  1858.     [EMSGSIZE] The socket requires that message be sent atomically, and
  1859.     the size of the message to be sent made this impossible.
  1860.  
  1861.     [EAGAIN] The socket is marked non-blocking and the requested
  1862.     operation would block.
  1863.  
  1864.     [ENOBUFS] The system was unable to allocate an internal buffer.  The
  1865.     operation may succeed when buffers become available.
  1866.  
  1867.     [ENOBUFS] The output queue for a network interface was full.  This
  1868.     generally indicates that the interface has stopped sending, but may
  1869.     be caused by transient congestion.
  1870.  
  1871.    INPUTS
  1872.     s - socket
  1873.  
  1874.     buf - buffer
  1875.  
  1876.     len - length
  1877.  
  1878.     flags - flags
  1879.  
  1880.    RESULT
  1881.     sendlen (D0) - length sent
  1882.  
  1883. bsdsocket.library/sendmsg                bsdsocket.library/sendmsg
  1884.  
  1885.    NAME
  1886.     sendmsg -- send data to a socket
  1887.  
  1888.    SYNOPSIS
  1889.     sendlen = sendmsg( s, msg, flags );
  1890.     D0           D0 A0   D1
  1891.  
  1892.     long sendmsg( long s, struct msghdr *msg, long flags );
  1893.  
  1894.    FUNCTION
  1895.     sendmsg() is used to transmit data to another socket.  For more
  1896.     information please see the description of send().
  1897.  
  1898.    INPUTS
  1899.     s - socket
  1900.  
  1901.     msg - message header
  1902.  
  1903.     flags - flags
  1904.  
  1905.    RESULT
  1906.     sendlen (D0) - length sent
  1907.  
  1908. bsdsocket.library/sendto                 bsdsocket.library/sendto
  1909.  
  1910.    NAME
  1911.     sendto -- send data to a socket
  1912.  
  1913.    SYNOPSIS
  1914.     sendlen = sendto( s, buf, len, flags, to, tolen );
  1915.     D0          D0 A0   D1   D2     A1  D3
  1916.  
  1917.     long sendto( long s, unsigned char *buf, long len, long flags, struct
  1918.         sockaddr *to, long tolen );
  1919.  
  1920.    FUNCTION
  1921.     sendmsg() is used to transmit data to another socket.  The address of
  1922.     the target is given by to with tolen specifying its size.  For more
  1923.     information please see the description of send().
  1924.  
  1925.    INPUTS
  1926.     s - socket
  1927.  
  1928.     buf - buffer
  1929.  
  1930.     len - length
  1931.  
  1932.     flags - flags
  1933.  
  1934.     to - address
  1935.  
  1936.     tolen - address length
  1937.  
  1938.    RESULT
  1939.     sendlen (D0) - length sent
  1940.  
  1941. bsdsocket.library/SetErrnoPtr            bsdsocket.library/SetErrnoPtr
  1942.  
  1943.    NAME
  1944.     SetErrnoPtr -- set the pointer to the errno variable
  1945.  
  1946.    SYNOPSIS
  1947.     SetErrnoPtr( errnop, size );
  1948.              A0      D0
  1949.  
  1950.     void SetErrnoPtr( void *errnop, long size );
  1951.  
  1952.    FUNCTION
  1953.     This function was deprecated.  Please use SocketBaseTags() with a
  1954.     code of SBTC_ERRNOPTR instead.
  1955.  
  1956.    INPUTS
  1957.     errnop - errno pointer
  1958.  
  1959.     size - size
  1960.  
  1961. bsdsocket.library/SetSocketSignals       bsdsocket.library/SetSocketSignals
  1962.  
  1963.    NAME
  1964.     SetSocketSignals -- set the socket signal mask
  1965.  
  1966.    SYNOPSIS
  1967.     SetSocketSignals( intmask, iomask, urgentmask );
  1968.               D0       D1       D2
  1969.  
  1970.     void SetSocketSignals( unsigned long intmask, unsigned long iomask,
  1971.         unsigned long urgentmask );
  1972.  
  1973.    FUNCTION
  1974.     This function was deprecated.  Please use SocketBaseTags() with codes
  1975.     of SBTC_BREAKMASK, SBTC_SIGIOMASK or SBTC_SIGURGMASK instead.
  1976.  
  1977.    INPUTS
  1978.     intmask - interrupt mask
  1979.  
  1980.     iomask - i/o mask
  1981.  
  1982.     urgentmask - urgent mask
  1983.  
  1984. bsdsocket.library/setsockopt             bsdsocket.library/setsockopt
  1985.  
  1986.    NAME
  1987.     setsockopt -- set options on sockets
  1988.  
  1989.    SYNOPSIS
  1990.     ret = setsockopt( s, level, optname, optval, optlen );
  1991.     D0          D0 D1     D2         A0      d3
  1992.  
  1993.     long setsockopt( long s, long level, long optname, void *optval, long
  1994.         optlen );
  1995.  
  1996.    FUNCTION
  1997.     setsockopt() sets the options associated with a socket.  Please see
  1998.     the description of getsockopt() for more information.
  1999.  
  2000.    INPUTS
  2001.     s - socket
  2002.  
  2003.     level - socket level
  2004.  
  2005.     optname - option name
  2006.  
  2007.     optval - option value
  2008.  
  2009.     optlen - length of option value
  2010.  
  2011.    RESULT
  2012.     ret (D0) - return code
  2013.  
  2014. bsdsocket.library/shutdown               bsdsocket.library/shutdown
  2015.  
  2016.    NAME
  2017.     shutdown -- shut down part of a full-duplex connection
  2018.  
  2019.    SYNOPSIS
  2020.     ret = shutdown( s, how );
  2021.     D0        D0 D1
  2022.  
  2023.     long shutdown( long s, long how );
  2024.  
  2025.    FUNCTION
  2026.     The shutdown() call causes all or part of a full-duplex connection on
  2027.     the socket associated with s to be shut down.  If how is 0, further
  2028.     receives will be disallowed.  If how is 1, further sends will be
  2029.     disallowed.  If how is 2, further sends and receives will be
  2030.     disallowed.
  2031.  
  2032.     A 0 is returned if the call succeeds, -1 if it fails.
  2033.  
  2034.     The call succeeds unless:
  2035.  
  2036.     [EBADF] S is not a valid descriptor.
  2037.  
  2038.     [ENOTCONN] The specified socket is not connected.
  2039.  
  2040.    INPUTS
  2041.     s - socket
  2042.  
  2043.     how - how
  2044.  
  2045.    RESULT
  2046.     ret (D0) - return code
  2047.  
  2048. bsdsocket.library/socket                 bsdsocket.library/socket
  2049.  
  2050.    NAME
  2051.     socket -- create an endpoint for communication
  2052.  
  2053.    SYNOPSIS
  2054.     s  = socket( domain, type, protocol );
  2055.     D0         D0      D1    D2
  2056.  
  2057.     long socket( long domain, long type, long protocol );
  2058.  
  2059.    FUNCTION
  2060.     socket() creates an endpoint for communication and returns a
  2061.     descriptor.
  2062.  
  2063.     The domain parameter specifies a communications domain within which
  2064.     communication will take place; this selects the protocol family which
  2065.     should be used.  These families are defined in the include file
  2066.     <sys/socket.h>.  The currently understood formats are
  2067.  
  2068.           AF_INET          (ARPA Internet protocols),
  2069.  
  2070.     The socket has the indicated type, which specifies the semantics of
  2071.     communication.    Currently defined types are:
  2072.  
  2073.           SOCK_STREAM
  2074.           SOCK_DGRAM
  2075.           SOCK_RAW
  2076.           SOCK_SEQPACKET
  2077.           SOCK_RDM
  2078.  
  2079.     A SOCK_STREAM type provides sequenced, reliable, two-way connection
  2080.     based byte streams.  An out-of-band data transmission mechanism may
  2081.     be supported.  A SOCK_DGRAM socket supports datagrams
  2082.     (connectionless, unreliable messages of a fixed (typically small)
  2083.     maximum length).  A SOCK_SEQPACKET socket may provide a sequenced,
  2084.     reliable, two-way connection-based data transmission path for
  2085.     datagrams of fixed maximum length; a consumer may be required to read
  2086.     an entire packet with each read system call.  This facility is
  2087.     protocol specific, and presently implemented only for PF_NS.
  2088.     SOCK_RAW sockets provide access to internal network protocols and
  2089.     interfaces.  The types SOCK_RAW and SOCK_RDM, which is planned, but
  2090.     not yet implemented, are not described here.
  2091.  
  2092.     The protocol specifies a particular protocol to be used with the
  2093.     socket.  Normally only a single protocol exists to support a
  2094.     particular socket type within a given protocol family.    However, it
  2095.     is possible that many protocols may exist, in which case a particular
  2096.     protocol must be specified in this manner.  The protocol number to
  2097.     use is particular to the communication domain in which communication
  2098.     is to take place.
  2099.  
  2100.     Sockets of type SOCK_STREAM are full-duplex byte streams, similar to
  2101.     pipes.    A stream socket must be in a connected state before any data
  2102.     may be sent or received on it.    A connection to another socket is
  2103.     created with a connect() call.    Once connected, data may be
  2104.     transferred using some variant of the send() and recv() calls.    When
  2105.     a session has been completed a CloseSocket() may be performed.
  2106.     Out-of-band data may also be transmitted as described in send() and
  2107.     received as described in recv().
  2108.  
  2109.     The communications protocols used to implement a SOCK_STREAM insure
  2110.     that data is not lost or duplicated.  If a piece of data for which
  2111.     the peer protocol has buffer space cannot be successfully transmitted
  2112.     within a reasonable length of time, then the connection is considered
  2113.     broken and calls will indicate an error with -1 returns and with
  2114.     ETIMEDOUT as the specific code in the global variable errno.  The
  2115.     protocols optionally keep sockets ``warm'' by forcing transmissions
  2116.     roughly every minute in the absence of other activity.    An error is
  2117.     then indicated if no response can be elicited on an otherwise idle
  2118.     connection for a extended period (e.g.    5 minutes).  A process is
  2119.     notified if it sends on a broken stream.
  2120.  
  2121.     SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM
  2122.     sockets.  The only difference is that recv() calls will return only
  2123.     the amount of data requested, and any remaining in the arriving
  2124.     packet will be discarded.
  2125.  
  2126.     SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to
  2127.     correspondents named in send() calls.  Datagrams are generally
  2128.     received with recvfrom(), which returns the next datagram with its
  2129.     return address.
  2130.  
  2131.     An IoctlSocket() call can be used to specify a process group to
  2132.     receive an "urgent" notification when the out-of-band data arrives.
  2133.     It may also enable non-blocking I/O and asynchronous notification of
  2134.     I/O events.
  2135.  
  2136.     The operation of sockets is controlled by socket level options.
  2137.     These options are defined in the file <sys/socket.h>.  setsockopt()
  2138.     and getsockopt() are used to set and get options, respectively.
  2139.  
  2140.     A -1 is returned if an error occurs, otherwise the return value is a
  2141.     descriptor referencing the socket.
  2142.  
  2143.     The socket() call fails if:
  2144.  
  2145.     [EPROTONOSUPPORT] The protocol type or the specified protocol is not
  2146.     supported within this domain.
  2147.  
  2148.     [EMFILE] The per-process descriptor table is full.
  2149.  
  2150.     [EACCESS] Permission to create a socket of the specified type and/or
  2151.     protocol is denied.
  2152.  
  2153.     [ENOBUFS] Insufficient buffer space is available.  The socket cannot
  2154.     be created until sufficient resources are freed.
  2155.  
  2156.    INPUTS
  2157.     domain - domain
  2158.  
  2159.     type - socket type
  2160.  
  2161.     protocol - protocol
  2162.  
  2163.    RESULT
  2164.     s (D0) - socket
  2165.  
  2166. bsdsocket.library/SocketBaseTagList      bsdsocket.library/SocketBaseTagList
  2167.  
  2168.    NAME
  2169.     SocketBaseTagList -- get/set global parameters
  2170.     SocketBaseTags -- Varargs stub for SocketBaseTagList().
  2171.  
  2172.    SYNOPSIS
  2173.     ret = SocketBaseTagList( tags );
  2174.     D0             A0
  2175.  
  2176.     long SocketBaseTagList( struct TagItem *tags );
  2177.  
  2178.     ret = SocketBaseTags( tag, ... );
  2179.  
  2180.     long SocketBaseTags( long tag, ... );
  2181.  
  2182.    FUNCTION
  2183.     SocketBaseTagList and its varargs equivalent, SocketBaseTags, are
  2184.     used to inspect and change global parameter in the protocol stack.
  2185.     All parameters are passed and retrieved via TagLists.  The ti_Tag
  2186.     field determines which parameter to inspect/change, and what to do
  2187.     with it.  The ti_Data field contains the value or a pointer to the
  2188.     value.
  2189.  
  2190.     All items passed in the ti_Tag field must have the general form
  2191.     SBTM_...(SBTC_...), where the SBTM_...    macro determines the type or
  2192.     access, and the SBTC_...  determines the item to be inspected or
  2193.     changed.  Possible SBTM_...  values include:
  2194.  
  2195.     SBTM_GETREF(SBTC_...): get by reference.  The ti_Data field needs to
  2196.     contain a pointer to a memory location where the kernel stores the
  2197.     current value of the selected item.
  2198.  
  2199.     SBTM_GETVAL(SBTC_...): get by value.  The kernel stores the current
  2200.     value directly in the ti_Data field.  This obviously only works for
  2201.     actual TagLists passed to SocketBaseTagList(), not for TagItems
  2202.     passed to SocketBaseTags() on the stack.
  2203.  
  2204.     SBTM_SETREF(SBTC_...): set by reference.  The ti_Data field contains
  2205.     a pointer to the new value of the selected item, which is copied by
  2206.     the kernel.
  2207.  
  2208.     SBTM_SETVAL(SBTC_...): set by value.  The ti_Data field contains the
  2209.     new value of the selected item, which is copied by the kernel.
  2210.  
  2211.     Note that some of the items (e.g.  SBTC_ERRNOBYTEPTR) already use
  2212.     pointers as parameters.  These pointers have nothing to do with the
  2213.     "by reference" argument passing mechanism.  If you pass these pointer
  2214.     by reference then ti_Data actually contains a pointer to a pointer.
  2215.  
  2216.     Possible SBTC_...  items are:
  2217.  
  2218.     SBTC_BREAKMASK: exec signal mask which corresponds to the EINTR
  2219.     signal (Ctrl-C), typically SIGBREAKF_CTRL_C.
  2220.  
  2221.     SBTC_DTABLESIZE: size of the socket descriptor table.  The default is
  2222.     64.
  2223.  
  2224.     SBTC_ERRNO: The current value of the errno variable.
  2225.  
  2226.     SBTC_ERRNOBYTEPTR, SBTC_ERRNOWORDPTR, SBTC_ERRNOLONGPTR,
  2227.     SBTC_ERRNOPTR(size): Link the program's global errno variable to the
  2228.     protocol stack's internal errno variable, by passing a pointer to the
  2229.     program's variable to the protocol stack.  If you use the "library
  2230.     auto-open" feature then this is done automatically for you.
  2231.  
  2232.     SBTC_ERRNOSTRPTR: Get the error string related to an error code.
  2233.     Only SBTM_GET...  is allowed.  In this special case ti_Data is an
  2234.     input/output parameter: the value passed to SocketBaseTagList() is
  2235.     the error code, and after SocketBaseTagList() has returned it has
  2236.     been replaced with a string pointer to the error string corresponding
  2237.     to the error code.
  2238.  
  2239.     SBTC_FDCALLBACK: Install a callback hook that is called by the kernel
  2240.     whenever the file descriptor table is modified.  This function should
  2241.     NOT be used by applications, and is intended for use within low-level
  2242.     link libraries or startup code only.  A full description is beyond
  2243.     the scope of this document.  Note: this option is deprecated because
  2244.     it does not handle mixed-CPU setups.  Use
  2245.     miami.library/MiamiGetFdCallback() and
  2246.     miami.library/MiamiSetFdCallback() in new code instead.
  2247.  
  2248.     SBTC_HERRNO: The current value of the h_errno variable (error code
  2249.     from the resolver).
  2250.  
  2251.     SBTC_HERRNOSTRPTR: Get the error string related to a resolver error
  2252.     code (i.e.  an error code in the h_errno variable).  Only SBTM_GET...
  2253.     is allowed.  In this special case ti_Data is an input/output
  2254.     parameter: the value passed to SocketBaseTagList() is the error code,
  2255.     and after SocketBaseTagList() has returned it has been replaced with
  2256.     a string pointer to the error string corresponding to the error code.
  2257.  
  2258.     SBTC_IOERRNOSTRPTR: Get the error string related to an AmigaOS I/O
  2259.     error code.  The use of this code is deprecated.
  2260.  
  2261.     SBTC_LOGFACILITY: Facility code for the syslog mechanism.
  2262.  
  2263.     SBTC_LOGMASK: Filter mask for syslog messages.
  2264.  
  2265.     SBTC_LOGSTAT: Syslog options.
  2266.  
  2267.     SBTC_LOGTAGPTR: Program identification for syslog messages.  If you
  2268.     use the "library auto-open" feature then this is set automatically
  2269.     for you.
  2270.  
  2271.     SBTC_S2ERRNOSTRPTR: Get the error string related to a SANA-II error
  2272.     code.  The use of this code is deprecated.
  2273.  
  2274.     SBTC_S2WERRNOSTRPTR: Get the error string related to a SANA-II wire
  2275.     error code.  The use of this code is deprecated.
  2276.  
  2277.     SBTC_SIGEVENTMASK: Exec signal mask for asynchronous event
  2278.     notification (see GetSocketEvents()).
  2279.  
  2280.     SBTC_SIGIOMASK: Exec signal mask for asynchronous socket events.  The
  2281.     use of this mechanism is deprecated.
  2282.  
  2283.     SBTC_SIGURGMASK: Exec signal mask for out-of-band data.  The use of
  2284.     this mechanism is deprecated.
  2285.  
  2286.     SocketBaseTagList()/SocketBaseTags() returns 0 on success, or a
  2287.     positive value n, where x is (index minus one) of the TagItem that
  2288.     caused the error.
  2289.  
  2290.    INPUTS
  2291.     tags - taglist
  2292.  
  2293.    RESULT
  2294.     ret (D0) - return code
  2295.  
  2296. bsdsocket.library/vsyslog                bsdsocket.library/vsyslog
  2297.  
  2298.    NAME
  2299.     vsyslog -- create a system log message
  2300.     syslog -- Varargs stub for vsyslog().
  2301.  
  2302.    SYNOPSIS
  2303.     vsyslog( pri, msg, args );
  2304.          D0   A0   A1
  2305.  
  2306.     void vsyslog( long pri, const char *msg, va_list args );
  2307.  
  2308.     syslog( pri, msg, arg1, ... );
  2309.  
  2310.     void syslog( long pri, const char *msg, long arg1, ... );
  2311.  
  2312.    FUNCTION
  2313.     The syslog() function writes message to the system message logger.
  2314.     The message is then written to the system log, in a protocol
  2315.     stack-dependent way.
  2316.  
  2317.     The message is identical to a printf() format string, except that
  2318.     `%m' is replaced by the current error message.    (As denoted by the
  2319.     internal variable errno.) A trailing newline is added if none is
  2320.     present.
  2321.  
  2322.     The vsyslog() function is an alternate form in which the arguments
  2323.     have already been captured using the variable-length argument
  2324.     facilities of varargs.
  2325.  
  2326.     The message is tagged with priority.  Priorities are encoded as a
  2327.     facility and a level.  The facility describes the part of the system
  2328.     generating the message.  The level is selected from the following
  2329.     ordered (high to low) list:
  2330.  
  2331.     LOG_EMERG A panic condition.  users.
  2332.  
  2333.     LOG_ALERT A condition that should be corrected immediately, such as a
  2334.     corrupted system database.
  2335.  
  2336.     LOG_CRIT Critical conditions, e.g., hard device errors.
  2337.  
  2338.     LOG_ERR Errors.
  2339.  
  2340.     LOG_WARNING Warning messages.
  2341.  
  2342.     LOG_NOTICE Conditions that are not error conditions, but should
  2343.     possibly be handled specially.
  2344.  
  2345.     LOG_INFO Informational messages.
  2346.  
  2347.     LOG_DEBUG Messages that contain information normally of use only when
  2348.     debugging a program.
  2349.  
  2350.    INPUTS
  2351.     pri - priority
  2352.  
  2353.     msg - message
  2354.  
  2355.     args - arguments
  2356.  
  2357. bsdsocket.library/WaitSelect             bsdsocket.library/WaitSelect
  2358.  
  2359.    NAME
  2360.     WaitSelect -- synchronous socket I/O multiplexing
  2361.  
  2362.    SYNOPSIS
  2363.     n  = WaitSelect( nfds, readfds, writefds, exceptfds, timeout,
  2364.     D0         D0    A0    A1      A2         A3
  2365.         signals );
  2366.         D0
  2367.  
  2368.     long WaitSelect( long nfds, fd_set *readfds, fd_set *writefds, fd_set
  2369.         *exceptfds, struct timeval *timeout, ULONG *signals );
  2370.  
  2371.    FUNCTION
  2372.     WaitSelect() is identical to select(), except that it takes an
  2373.     additional parameter: a pointer to an exec signal mask.
  2374.  
  2375.     If the pointer is NULL or points to a an empty mask then WaitSelect()
  2376.     behaves like select().
  2377.  
  2378.     If the mask pointed to is non-null then WaitSelect() returns if any
  2379.     of these signals has been received.  In this case WaitSelect()
  2380.     returns 0, the mask is changed to reflect only those signals that
  2381.     have occured, and the kernel has reset the signals in exec's Task
  2382.     structure.
  2383.  
  2384.     For more information please see the description of select().
  2385.  
  2386.    INPUTS
  2387.     nfds - number of socket descriptors
  2388.  
  2389.     readfds - read fd set
  2390.  
  2391.     writefds - write fd set
  2392.  
  2393.     exceptfds - exception fd set
  2394.  
  2395.     timeout - timeout
  2396.  
  2397.     signals - signal mask pointer
  2398.  
  2399.    RESULT
  2400.     n (D0) - numbere of socket descriptors
  2401.  
  2402.